Skip to main content

MCP Server

The data in your lakehouse is available to AI agents through DataStori's MCP server. It gives read-only access to the Delta tables in the authenticated customer's lakehouse. Tables are discovered under that bucket's silver and gold folders.

The server is available at https://explore.datastori.io/mcp. Connecting requires a Bearer token, which you generate from the DataStori portal.

Agents should list the tables, describe the ones they need, and then query them. If a table you expect is missing, refresh the table list once.

note

The Data Exploration Agent uses this MCP server to fetch and show your data.

Tools​

  • list_tables. Lists the Delta tables available to query, with a description for each. A table that failed to load is marked unavailable and includes the error.

  • refresh_tables. Re-scans the customer's S3 folders for Delta tables without restarting the server. Use it when list_tables is missing a table that should exist, for example after new data was ingested, or to retry a table that failed to load. The result reports which tables were added, removed, had their location changed, were retried, or failed. If the scan itself fails, the existing tables are left unchanged. Only one refresh can run at a time for a customer. Refresh updates the server's table list only. It does not change the data.

  • describe_table. Describes one table: columns and types, partition columns, Delta version, file count, size, and an approximate row count. Pass an optional Delta version to inspect an earlier version of the table.

  • sample_table. Returns a few rows so you can see what the data looks like. The default is 10 rows, and the server caps the limit. Pass an optional Delta version to sample an earlier version.

  • run_query. Runs one read-only SQL query: a single SELECT, or a WITH that ends in a SELECT. Reference tables by the names returned from list_tables. Table functions, file paths, and any write or DDL statement are rejected. Results are capped, and truncated is true when more rows were available. Filter on partition columns and add a LIMIT when exploring.

  • table_history. Shows recent commits for a table: version, timestamp, and operation. The default is 10 commits, and the maximum is 100.

Connect​

Generate a Bearer token in the DataStori portal. Every client below sends it on the request as:

Authorization: Bearer <token>

Replace <token> with the token from the portal. Do not commit the token to a repository.

Claude​

Claude Desktop connects to a remote MCP server from its config file.

  1. Generate a Bearer token in the portal.
  2. Open the Claude Desktop config file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json
  3. Add the DataStori server. If mcpServers already exists, add datastori inside it.
{
  "mcpServers": {
    "datastori": {
      "url": "https://explore.datastori.io/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
  1. Save the file and restart Claude Desktop.
  2. In a new chat, confirm DataStori is connected, then ask Claude to call list_tables.

Cursor​

  1. Generate a Bearer token in the portal.
  2. Open Cursor Settings → MCP and add a new MCP server, or create the config file yourself:
    • Project: .cursor/mcp.json in the project root
    • All projects: ~/.cursor/mcp.json
  3. Use this configuration:
{
  "mcpServers": {
    "datastori": {
      "url": "https://explore.datastori.io/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
  1. Save the file. Cursor shows the server under MCP. If it does not connect, reload the window.
  2. In Agent chat, ask Cursor to call list_tables. The DataStori tools are available once the server shows as connected.

Python​

The server uses the streamable HTTP transport. Install the official MCP client (mcp 1.12 or later) and pass the Bearer token in the request headers.

pip install "mcp>=1.12"
import asyncio
import os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://explore.datastori.io/mcp"
TOKEN = os.environ["DATASTORI_API_KEY"]


async def main() -> None:
    headers = {"Authorization": f"Bearer {TOKEN}"}
    async with streamablehttp_client(URL, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([tool.name for tool in tools.tools])

            tables = await session.call_tool("list_tables", {})
            print(tables.structuredContent)


if __name__ == "__main__":
    asyncio.run(main())

Run it with the portal token in the environment:

DATASTORI_API_KEY='<token>' python connect.py

A missing or wrong token returns 401 unauthorized. After list_tables succeeds, call describe_table and then run_query.

MCP deployment modes​

DataStori hosts the MCP server at https://explore.datastori.io/mcp. That is the server the connection steps above use.

You can also have the MCP server deployed in your own cloud, so it runs next to your lakehouse. Contact the DataStori support team at contact@datastori.io to set that up.